/**
 * Copyright 2008 Benjamin Possolo
 * 
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 * 
 *     http://www.apache.org/licenses/LICENSE-2.0
 * 
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.javenue.util.process;

/**
 * Callback interface for business operations that are to be executed in a transactional fashion
 * and which alter a process's state.
 * <p>
 * A <tt>TransitionWithResult</tt>'s <code>doTransition()</code> method can be annotated
 * <tt>@Idempotent</tt> which means the code within the method will be automatically 
 * reattempted in the case of failure.
 * <p>
 * A <tt>Process</tt> that executes <tt>TransitionWithResult</tt> objects via a <tt>TransitionManager</tt>
 * can optionally have its <code>processState</code> managed by the <tt>TransitionManager</tt>. When a 
 * <tt>Process</tt>'s <code>stateManaged</code> flag is set to <code>true</code> then the 
 * <tt>TransitionManager</tt> will automatically load the <code>processState</code> for the process 
 * from the persistence store, inject it into the <tt>Process</tt> instance before the 
 * <code>doTransition()</code> method is invoked. If the <code>doTransition()</code> method 
 * completes without throwing a runtime exception, then the <tt>TransitionManager</tt> will 
 * automatically persist/commit the <code>processState</code> object back to the persistence store.
 * <p>
 * If a process's <code>stateManaged</code> flag is set to <code>false</code>, then the code within
 * the <code>doTransition()</code> method will simply be executed by the <tt>TransitionManager</tt>
 * in a transactional fashion.
 * 
 * @see TransitionManager
 * @see Transition
 * @author Benjamin Possolo
 * <p>Created on Jun 29, 2008
 */
public interface TransitionWithResult {
	
	/**
	 * The designer of a <tt>Process</tt> should place transactional business operations and any
	 * operations that alter the <code>processState</code> object within an implementation
	 * of this method. Runtime exceptions thrown within this method will be caught by the
	 * <tt>TransitionManager</tt> and wrapped in a <tt>TransitionException</tt> before being
	 * passed up to the executing process.
	 * <p>
	 * This method is invoked by a <tt>TransitionManager</tt>.
	 * <p>
	 * User code may return a value from within the <code>doTransition()</code> method.
	 * The return value is returned to the process that executed this callback via a
	 * <tt>TransitionManager</tt>. If user code does not need to return a value from 
	 * within the <code>doTransition()</code> method, then the <tt>Transition</tt> 
	 * interface should be used instead.
	 * <p>
	 * This method can be annotated <tt>@Idempotent</tt> which
	 * means the code within the method will be automatically reattempted 
	 * in the case of failure.
	 * 
	 * @return a user-defined object that will be returned back to the process that executed this transition
	 */
	Object doTransition();

}
